
<!--generated with sswg-->
<style>
    html {max-width: 100%; margin: auto; color: #333333;}
    a.button {padding: 15px 32px; background-color: #555; border-radius: 2em; border-width: 0px; text-decoration: none; color: white; font-size: 25.0px; line-height: 2.5em;}
    a.button:hover {background-color: #777}
    a.button_big {padding: 0.5em; background-image: linear-gradient(to top, #427b0e, #9ba97d); background-color: lightgray; background-blend-mode: multiply; border-radius: .75em; border-width: 0px; text-decoration: none; min-width: 150px; max-width: 150px; min-height: 150px; max-height: 150px; display: inline-block; vertical-align: top; margin: 4px 4px 10px 4px; color: white; font-size: 25.0px; background-size: auto 100%; background-position-x: center;}
    a.button_big:hover {background-color: white; color: #e6d23f; text-decoration: underline;}
    mark {background: #ccff99;}
    span {background-color: rgba(0, 0, 0, 0.55); padding: .1em; line-height: 1.35em;}
    img {max-width: 100%; vertical-align: top;}
    .code_block {background-color: whitesmoke; padding: 10px; margin: 0; font-family: monospace; font-size: 20; font-weight: normal; white-space: pre;}

    purple {color: hsl(289.0, 50%, 50%);}
    gray {color: gray;}
    olive {color: olive;}
    yellow {color: darkgoldenrod;}
    green {color: seagreen;}
    blue {color: hsl(210, 50%, 50%);}

</style>
<html>
<left>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title> entity basics</title>
<br>

<div style="text-align: center;max-width: 1000px; margin: auto;font-family: arial;">
<div style="font-size: 100.0px;font-weight: bold;">
Entity Basics<br>
<div style="font-size: 20.0px;font-weight: normal;">
<br>
<br>
<div style="text-align: left;">
<div style="font-size: 40.0px;font-weight: bold;">
<div id="What is an Entity?"/><br>
What is an Entity?<br>
<div style="font-size: 20.0px;font-weight: normal;">
<br>
&nbsp;&nbsp;&nbsp;&nbsp;An entity is a thing in the world, and is the "god class" in ursina.<br>
&nbsp;&nbsp;&nbsp;&nbsp;It's like a GameObject in Unity or an Actor in Unreal.<br>
<br>
&nbsp;&nbsp;&nbsp;&nbsp;It can have a position, rotation, and scale.<br>
&nbsp;&nbsp;&nbsp;&nbsp;It can have a model, texture and color.<br>
&nbsp;&nbsp;&nbsp;&nbsp;It can have an update function, input function and scripts.<br>
&nbsp;&nbsp;&nbsp;&nbsp;For an overview of all its attributes and functions, see <a href="https://www.ursinaengine.org/cheat_sheet.html#Entity">https://www.ursinaengine.org/cheat_sheet.html#Entity</a><br>
<br>
<br>
<br>
<div style="font-size: 40.0px;font-weight: bold;">
<div id="Setting a model"/><br>
Setting a model<br>
<div style="font-size: 20.0px;font-weight: normal;">
<br>
&nbsp;&nbsp;&nbsp;&nbsp;There are several included models like 'quad', 'plane', 'cube' and 'sphere',<br>
&nbsp;&nbsp;&nbsp;&nbsp;but you can also use your own.<br>
&nbsp;&nbsp;&nbsp;&nbsp;To do that simply give the base name of your model and it will glob/search for<br>
&nbsp;&nbsp;&nbsp;&nbsp;the model and take the first one it finds.<br>
<br>
&nbsp;&nbsp;&nbsp;&nbsp;Supported file types are:<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;* obj<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;* bam (binary format)<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;* blend (gets auto converted to an obj)<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;* ursinamesh (custom human readable format identical to how you'd make a Mesh in code)<br>
<br>
<div class="code_block" style="margin-left: 1em;"><olive>Entity</olive>(<olive>model</olive>=<green>'name_of_your_model'</green>)
</div><br>
<br>
<br>
<div style="font-size: 40.0px;font-weight: bold;">
<div id="Texture"/><br>
Texture<br>
<div style="font-size: 20.0px;font-weight: normal;">
<br>
&nbsp;&nbsp;&nbsp;&nbsp;Setting a texture is similar to setting a model. Just give it a name in this case as well:<br>
<br>
<div class="code_block" style="margin-left: 1em;">e<yellow>1</yellow> = <olive>Entity</olive>(<olive>model</olive>=<green>'cube'</green>, <olive>texture</olive>=<green>'texture_name'</green>)

<gray># other ways are:</gray>
e<yellow>2</yellow> = <olive>Entity</olive>(<olive>model</olive>=<green>'cube'</green>, <olive>texture</olive>=e<yellow>1</yellow>.texture) <gray># or set it to another Texture</gray>
e<yellow>3</yellow> = <olive>Entity</olive>(<olive>model</olive>=<green>'cube'</green>, <olive>texture</olive>=PIL.Image.new(<olive>mode</olive>="RGBA", size=(<yellow>8</yellow><yellow>5</yellow><yellow>4</yellow>,<yellow>4</yellow><yellow>8</yellow><yellow>0</yellow>))) <gray># set a PIL texture</gray>
e<yellow>4</yellow> = <olive>Entity</olive>(<olive>model</olive>=<green>'cube'</green>, <olive>texture</olive>=<green>'movie_name.mp<yellow>4</yellow>'</green>) <gray># set video texture</gray>
</div><br>
&nbsp;&nbsp;&nbsp;&nbsp;For 2d graphics there's also the Sprite class, which is simply an Entity with a<br>
&nbsp;&nbsp;&nbsp;&nbsp;'quad' model and scale&nbsp;&nbsp;set to automatically fit the size and aspect ratio of the texture.<br>
<br>
<div class="code_block" style="margin-left: 1em;">s = Sprite(<green>'texture_name'</green>)
<blue>print</blue>(s.aspect_ratio)
</div><br>
<br>
<br>
<div style="font-size: 40.0px;font-weight: bold;">
<div id="Setting the color"/><br>
Setting the color<br>
<div style="font-size: 20.0px;font-weight: normal;">
<br>
<div class="code_block" style="margin-left: 1em;">e.color = color.red <gray># set it to a color in the color module</gray>

e.color = color.color(<yellow>1</yellow><yellow>2</yellow><yellow>0</yellow>, .<yellow>5</yellow>, .<yellow>5</yellow>) <gray># hsv color</gray>
e.color = color.rgb(.<yellow>8</yellow>, .<yellow>1</yellow>, <yellow>0</yellow>) <gray># rgb color</gray>
e.color = e.color.tint(.<yellow>1</yellow>) <gray># tint the color</gray>
e.color = color.random_color() <gray># set it to a random color</gray>
e.color = lerp(color.red, color.green, .<yellow>5</yellow>) <gray># set it to a color half way between red and green</gray>
</div><br>
<br>
<br>
<div style="font-size: 40.0px;font-weight: bold;">
<div id="Moving"/><br>
Moving<br>
<div style="font-size: 20.0px;font-weight: normal;">
<br>
&nbsp;&nbsp;&nbsp;&nbsp;You can move an entity by setting the attributes:<br>
&nbsp;&nbsp;&nbsp;&nbsp;'position', 'x', 'y', 'z', 'world_position', 'world_x', 'world_y', 'world_z'<br>
<br>
<div class="code_block" style="margin-left: 1em;"><gray># you can give it a position when you create i, or you can omit it and set it later</gray>
e = <olive>Entity</olive>(<olive>position</olive>=(<yellow>0</yellow>,<yellow>0</yellow>,<yellow>0</yellow>))
<gray># set position relative to parent entity:</gray>
e.position = Vec3(<yellow>0</yellow>,<yellow>0</yellow>,<yellow>0</yellow>)
e.position = Vec2(<yellow>0</yellow>,<yellow>0</yellow>)
e.position = (<yellow>0</yellow>,<yellow>0</yellow>,<yellow>0</yellow>)
e.position = (<yellow>0</yellow>,<yellow>0</yellow>)

<gray># shortcuts <purple>for</purple> individual axes:</gray>
e.x = <yellow>0</yellow>
e.y = <yellow>0</yellow>
e.z = <yellow>0</yellow>

    <gray># set position relative to the world:</gray>
e.world_position = (<yellow>0</yellow>,<yellow>0</yellow>,<yellow>0</yellow>)
</div><br>
&nbsp;&nbsp;&nbsp;&nbsp;See <a href="https://www.ursinaengine.org/coordinate_system.html">https://www.ursinaengine.org/coordinate_system.html</a> for more<br>
&nbsp;&nbsp;&nbsp;&nbsp;information on how the coordinate system works.<br>
<br>
<br>
<br>
<div style="font-size: 40.0px;font-weight: bold;">
<div id="Rotating"/><br>
Rotating<br>
<div style="font-size: 20.0px;font-weight: normal;">
<br>
<div class="code_block" style="margin-left: 1em;">e.rotation = (<yellow>0</yellow>,<yellow>0</yellow>,<yellow>0</yellow>)
e.rotation_y = <yellow>9</yellow><yellow>0</yellow>
</div><br>
&nbsp;&nbsp;&nbsp;&nbsp;The look_at() method can also be for pointing an entity at something:<br>
<br>
<div class="code_block" style="margin-left: 1em;">other entity = <olive>Entity</olive>(<olive>position</olive>=(<yellow>1</yellow><yellow>0</yellow>,<yellow>1</yellow>,<yellow>8</yellow>))

e.look_at(other_entity) <gray># make z-axis(forward) point at other_entity</gray>
e.look_at(other_entity, axis=<green>'up'</green>) <gray># optinally define which axis</gray>
</div><br>
<br>
<br>
<div style="font-size: 40.0px;font-weight: bold;">
<div id="Scaling"/><br>
Scaling<br>
<div style="font-size: 20.0px;font-weight: normal;">
<br>
&nbsp;&nbsp;&nbsp;&nbsp;Change the size of the entity by setting the scale attribute:<br>
<br>
<div class="code_block" style="margin-left: 1em;">e = <olive>Entity</olive>(<olive>model</olive>=<green>'cube'</green>, <olive>scale</olive>=(<yellow>3</yellow>,<yellow>1</yellow>,<yellow>1</yellow>))
</div><br>
<br>
<br>
<div style="font-size: 40.0px;font-weight: bold;">
<div id="Update"/><br>
Update<br>
<div style="font-size: 20.0px;font-weight: normal;">
<br>
&nbsp;&nbsp;&nbsp;&nbsp;An Entity's update method will be called automatically:<br>
<br>
<div class="code_block" style="margin-left: 1em;">e = <olive>Entity</olive>()
<purple>def</purple> my_update():
    e.x += <yellow>1</yellow> * time.dt <gray># dt is short <purple>for</purple> delta time, the duration since the last frame.</gray>

e.update = my_update
</div><br>
&nbsp;&nbsp;&nbsp;&nbsp;Or you can implement it by inheriting the Entity class:<br>
<br>
<div class="code_block" style="margin-left: 1em;">class Player(<olive>Entity</olive>):
    <purple>def</purple> update(self):
        self.x += <yellow>1</yellow> * time.dt
</div><br>
<br>
<br>
<div style="font-size: 40.0px;font-weight: bold;">
<div id="Input"/><br>
Input<br>
<div style="font-size: 20.0px;font-weight: normal;">
<br>
&nbsp;&nbsp;&nbsp;&nbsp;The same goes for the input method:<br>
<br>
<div class="code_block" style="margin-left: 1em;">class Player(<olive>Entity</olive>):
    <purple>def</purple> input(self, key):
        <purple>if</purple> key == <green>'w'</green>:
            self.position += self.forward

        <purple>if</purple> key == <green>'d'</green>:
            self.animate(<green>'rotation_y'</green>, self.rotation_y + <yellow>9</yellow><yellow>0</yellow>, duration=.<yellow>1</yellow>)

        <purple>if</purple> key == <green>'a'</green>:
            self.animate(<green>'rotation_y'</green>, self.rotation_y - <yellow>9</yellow><yellow>0</yellow>, duration=.<yellow>1</yellow>)
</div><br>
<br>
<div style="font-size: 40.0px;font-weight: bold;">
<div id="Mouse Input"/><br>
Mouse Input<br>
<div style="font-size: 20.0px;font-weight: normal;">
<br>
&nbsp;&nbsp;&nbsp;&nbsp;Entities can react to the mouse as long as they have collider.<br>
&nbsp;&nbsp;&nbsp;&nbsp;Buttons will have one by default, but you can also assign one.<br>
<br>
&nbsp;&nbsp;&nbsp;&nbsp;To get the entity currently under the mouse:<br>
<div class="code_block" style="margin-left: 1em;"><blue>print</blue>(mouse.entity)
</div><br>
&nbsp;&nbsp;&nbsp;&nbsp;To check if and entity with a collider is hovered by the mouse:<br>
<div class="code_block" style="margin-left: 1em;"><blue>print</blue>(my_entity.hovered)
</div><br>
&nbsp;&nbsp;&nbsp;&nbsp;There are also functions for handling mouse clicks and hover/unhover.<br>
&nbsp;&nbsp;&nbsp;&nbsp;These only works if the Entity has a collider and the function/callable is assigned.<br>
<br>
<div class="code_block" style="margin-left: 1em;">on_click()
on_double_click()
on_mouse_enter()
on_mouse_exit()
</div><br>
&nbsp;&nbsp;&nbsp;&nbsp;Example:<br>
<div class="code_block" style="margin-left: 1em;"><purple>def</purple> action():
    <blue>print</blue>(<green>'Ow! That hurt!'</green>)

<olive>Entity</olive>(<olive>model</olive>=<green>'quad'</green>, <olive>parent</olive>=camera.ui, <olive>scale</olive>=.<yellow>1</yellow>, <olive>collider</olive>=<green>'box'</green>, <olive>on_click</olive>=action) <gray># on_click should be a function/callable/Func/Sequence</gray>
</div><br>
&nbsp;&nbsp;&nbsp;&nbsp;on_mouse_enter and on_mouse_exit example:<br>
<div class="code_block" style="margin-left: 1em;">b = Button(<olive>scale</olive>=(.<yellow>5</yellow>, .<yellow>2</yellow><yellow>5</yellow>), <olive>text</olive>=<green>'zzz'</green>)
b.on_mouse_enter = Func(setattr, b, <green>'text'</green>, <green>'Hi, friend :D'</green>)
b.on_mouse_exit = Func(setattr, b, <green>'text'</green>, <green><green>''</green></green><green>'No! Don'</green>t leave me ;-;<green><green>''</green></green>')
</div><br>
<br>
<div style="font-size: 40.0px;font-weight: bold;">
<div id="Other Magic Functions"/><br>
Other Magic Functions<br>
<div style="font-size: 20.0px;font-weight: normal;">
<br>
&nbsp;&nbsp;&nbsp;&nbsp;Sometimes you want side effects when you enable/diable and entity, like play an animation or something.<br>
<br>
<div class="code_block" style="margin-left: 1em;">on_enable()
on_disable()
</div><br>
<br>
<br>
<br>
<br>

</html>
